package org.atlantis.grosbeak.castor;

import java.lang.reflect.Type;

/**
 * 转换器最上层接口。可以选择继承AbstractCastor这个抽象类（该抽象类通过反射机制能自动获取泛型参数FROM、TO的类型）。<br>
 * <font color="#FF0000"> <b>特别注意：</b><br>
 * 如果FROM、TO中存在泛型类型（如List&lt;String&gt;、Set&lt;String&gt;……）
 * 那么转换器会忽略泛型直接按照声明此泛型类型的类或接口（如List 、Set……）来
 * 进行转型。如下面两种转换器框架会做同样处理（只不过添加到转换器容器中时，后一种会替换前一种）：
 * <ol>
 * <li>public String2IntList implements Castor&lt;String,
 * List&lt;Integer&gt;&gt;{...}</li>
 * <li>public String2StrList implements Castor&lt;String,
 * List&lt;String&gt;&gt;{...}</li>
 * </ol>
 * </font>
 * 
 * @author <a href="mailto:seenoevil.cn@gmail.com">SeeNoEvil</a>
 * 
 * @param <FROM>
 *            需要转换的类型。
 * @param <TO>
 *            转换到的类型。
 */
public interface Castor<FROM, TO> {

	/**
	 * 需要转换的类型。
	 * 
	 * @return 需要转换的类型。
	 */
	Type getFrom();

	/**
	 * 需要转换到的类型。
	 * 
	 * @return 需要转换到的类型。
	 */
	Type getTo();

	/**
	 * 正向转换（从FROM类型到TO类型）。
	 * 
	 * @param src
	 *            需要进行类型转换的对象。
	 * @param toType
	 *            转换到的类型。
	 * @return 转换后的对象。
	 */
	TO obverseCast(FROM src, Class<?> toType) throws FailToCastException;

	/**
	 * 逆向转换转换（从TO类型到FROM类型）。
	 * 
	 * @param src
	 *            需要进行转换的对象。
	 * @param toType
	 *            转化到的类型。
	 * @return 转换后的对象。
	 */
	FROM reverseCast(TO src, Class<?> toType) throws FailToCastException;
}
